<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Policies Have Sensible Defaults</title>
<link rel="stylesheet" href="../../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Math Toolkit 3.3.0">
<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
<link rel="prev" href="what_is_a_policy.html" title="So Just What is a Policy Anyway?">
<link rel="next" href="policy_usage.html" title="So How are Policies Used Anyway?">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="what_is_a_policy.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="policy_usage.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="math_toolkit.pol_tutorial.policy_tut_defaults"></a><a class="link" href="policy_tut_defaults.html" title="Policies Have Sensible Defaults">Policies
      Have Sensible Defaults</a>
</h3></div></div></div>
<p>
        Most of the time you can just ignore the policy framework.
      </p>
<p>
        <span class="emphasis"><em>*The defaults for the various policies are as follows, if these
        work OK for you then you can stop reading now!</em></span>
      </p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Domain Error</span></dt>
<dd><p>
              Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code> exception.
            </p></dd>
<dt><span class="term">Pole Error</span></dt>
<dd><p>
              Occurs when a function is evaluated at a pole: throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code> exception.
            </p></dd>
<dt><span class="term">Overflow Error</span></dt>
<dd><p>
              Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code> exception.
            </p></dd>
<dt><span class="term">Underflow</span></dt>
<dd><p>
              Ignores the underflow, and returns zero.
            </p></dd>
<dt><span class="term">Denormalised Result</span></dt>
<dd><p>
              Ignores the fact that the result is denormalised, and returns it.
            </p></dd>
<dt><span class="term">Rounding Error</span></dt>
<dd><p>
              Throws a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">rounding_error</span></code> exception.
            </p></dd>
<dt><span class="term">Internal Evaluation Error</span></dt>
<dd><p>
              Throws a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">evaluation_error</span></code> exception.
            </p></dd>
<dt><span class="term">Indeterminate Result Error</span></dt>
<dd><p>
              Returns a result that depends on the function where the error occurred.
            </p></dd>
<dt><span class="term">Promotion of float to double</span></dt>
<dd><p>
              Does occur by default - gives full float precision results.
            </p></dd>
<dt><span class="term">Promotion of double to long double</span></dt>
<dd><p>
              Does occur by default if long double offers more precision than double.
            </p></dd>
<dt><span class="term">Precision of Approximation Used</span></dt>
<dd><p>
              By default uses an approximation that will result in the lowest level
              of error for the type of the result.
            </p></dd>
<dt><span class="term">Behaviour of Discrete Quantiles</span></dt>
<dd>
<p>
              The quantile function will by default return an integer result that
              has been <span class="emphasis"><em>rounded outwards</em></span>. That is to say lower
              quantiles (where the probability is less than 0.5) are rounded downward,
              and upper quantiles (where the probability is greater than 0.5) are
              rounded upwards. This behaviour ensures that if an X% quantile is requested,
              then <span class="emphasis"><em>at least</em></span> the requested coverage will be present
              in the central region, and <span class="emphasis"><em>no more than</em></span> the requested
              coverage will be present in the tails.
            </p>
<p>
              This behaviour can be changed so that the quantile functions are rounded
              differently, or even return a real-valued result using <a class="link" href="../pol_overview.html" title="Policy Overview">Policies</a>.
              It is strongly recommended that you read the tutorial <a class="link" href="understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
              Quantiles of Discrete Distributions</a> before using the quantile
              function on a discrete distribution. The <a class="link" href="../pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
              docs</a> describe how to change the rounding policy for these distributions.
            </p>
</dd>
</dl>
</div>
<p>
        What's more, if you define your own policy type, then it automatically inherits
        the defaults for any policies not explicitly set, so given:
      </p>
<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
<span class="comment">//</span>
<span class="comment">// Define a policy that sets ::errno on overflow, and does</span>
<span class="comment">// not promote double to long double internally:</span>

<span class="keyword">typedef</span> <span class="identifier">policy</span>
<span class="special">&lt;</span>
  <span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
  <span class="identifier">promote_double</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;</span>
<span class="special">&gt;</span> <span class="identifier">my_policy</span><span class="special">;</span>
</pre>
<p>
        then <code class="computeroutput"><span class="identifier">my_policy</span></code> defines a
        policy where only the overflow error handling and <code class="computeroutput"><span class="keyword">double</span></code>-promotion
        policies differ from the defaults.
      </p>
<p>
        We can also add a desired precision, for example, 9 bits or 3 decimal digits,
        to an error-handling policy, usually to trade precision for speed:
      </p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span> <span class="identifier">digit2</span><span class="special">&lt;</span><span class="number">9</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">my_policy</span><span class="special">;</span>
</pre>
<p>
        Or if you want to further modify an existing user policy, use <code class="computeroutput"><span class="identifier">normalise</span></code>:
      </p>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">normalise</span><span class="special">;</span>

<span class="keyword">typedef</span> <span class="identifier">normalise</span><span class="special">&lt;</span><span class="identifier">my_policy</span><span class="special">,</span> <span class="identifier">digits2</span><span class="special">&lt;</span><span class="number">9</span><span class="special">&gt;&gt;::</span><span class="identifier">type</span> <span class="identifier">my_policy_9</span><span class="special">;</span> <span class="comment">// errno on error, and limited precision.</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
      Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
      Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
      Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
      Walker and Xiaogang Zhang<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="what_is_a_policy.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="policy_usage.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
